[SLES-2971] feat(traces): gate X-Ray-driven sampling behind DD_MERGE_XRAY_TRACES - #1337

Stacked on #1325 — review that first; this diff is only the gate.

Problem

After #1325, an AWS-generated Sampled=1 still becomes an explicit Datadog priority of 1. X-Ray's sampling decision therefore still drives Datadog's, and a user who wants their own sampling to govern has no way to decline.

The tracer libraries make this opt-in through DD_MERGE_XRAY_TRACES (DD_MERGE_DATADOG_XRAY_TRACES in Ruby), which defaults to false. bottlecap has never read it.

Background

For an SQS trigger, the extension falls back to the X-Ray AWSTraceHeader when the record carries no _datadog attribute. Any Lambda→SQS→Lambda chain has such a header, because the AWS SDKs plant one for recursion detection, so this fallback fires for pipelines that have nothing to do with X-Ray.

Change

Adds a merge_xray_traces config (DD_MERGE_XRAY_TRACES, default false) and gates the flag on it:

let honor_sampled_flag = datadog_planted || merge_xray_traces;

"Datadog-planted" means the root id carries the …-00000000<16 hex> padding a Datadog library writes; anything else is AWS-generated. Only the last row moves with the flag.

Default false, so behavior holds at #1325's until a user opts in.

Datadog-planted headers stay ungated

dd-trace-java plants context in this same header for SQS, and it is the only carrier for JMS→SQS. Gating that on an X-Ray flag would break Datadog-to-Datadog propagation for users with no X-Ray involvement.

Correlation stays ungated

Trace and parent ids come from an AWS-generated header in both states. That is how bottlecap has always behaved, it costs no spans, and gating it would leave the reporting customer with their spans restored but their producer→consumer link gone.

Turning merging on reinstates the drop

With merging on, an AWS-generated Sampled=0 drops the trace, which is the reported behavior — restored deliberately for anyone who asks for it, since the flag means X-Ray's decisions count.

Where the flag is read

Off the propagator, which already carries the config to every extraction site. Threading the config explicitly would touch five more files, including two request-state tuples.

Naming

This reuses DD_MERGE_XRAY_TRACES rather than introducing a new variable, so users find the setting where they already expect it. That broadens what the name covers: the docs currently scope trace merging to Node.js and Python and describe it as merging X-Ray's own spans, so they need a line for this path.

Testing

Verified live on the SLES-2971 repro (Go, arm64, provided.al2023, SQS trigger), sending each header shape in both flag states. Every span in the trace carried the priority shown.

Only the AWS-generated Sampled=0 row moves with the flag, which is the intent. A trace id was present in all eight runs, so correlation is unaffected either way.

🤖 Generated with Claude Code